All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class quicktime.app.time.Timer

java.lang.Object
   |
   +----quicktime.app.time.Timer

public class Timer
extends Object
implements Timeable

This class provides timing services for either a subclass or a target object that implements the Ticklish interface. The Timer invokes the tickle method based on the rate that it is ticking and the scale and period of the timer itself. For instance

10 scale, 1 period => the tickle method is invoked 10 times a second at a rate of 1
1 scale, 1 period => the tickle method is invoked 1 time a second at a rate of 1
1 scale, 2 period => the tickle method is invoked every 2 seconds at a rate of 1
3 scale, 2 period => the tickle method is invoked 3 times every 2 seconds at a rate of 1

The Timer uses a quicktime TimeBase object as its time base. The timer's TimeBase can be slaved to or be a master of any other TimeBase. If this relationship is established the actual or effective rate of the TimeBase is determined by the rate of its own TimeBase and the rates of all of its master TimeBases.

The Timer can be in one of three states.

Active and tickling - in which case it issues both timeChanged and tickle calls
Active and not tickling - in which case it issues timeChanged calls but not tickle calls
Inactive - neither timeChanged or tickle calls are issued.

By default a Timer is inactive and an application using a Timer must make it active. A Timer will once active, tickle if tickling is enabled (which is the default setting). If an application wants to use a Timer without its tickle services, it can disable the tickle capability and reenable it later if appropriate.

Whenever the condition of the time base's time line changes the Timer notifies its subclass or Ticklish target through invoking the timeChanged method with the new time. The conditions under which this method is invoked are when the time value jumps or the effective rate changes from positive to negative or vice versa.

Whenever the tickle method is invoked the effective rate of the Timer's TimeBase is passes on, as is the time of the tickle method. In both cases this time value is specified in terms of the Ticklish.kScale value. If the timer is ticking (ie. its effective rate is not equal to zero) then the time when a timeChanged notification was sent will also be the time value that the next tickle method will receive.

If the tickle method returns true then the Timer will tickle again when the specified scale and period has elapsed. If the tickle method returns false then the Timer will not tickle again until the Timer's tickling has been reenabled.

The Timer is not interrupt driven so it does not guarantee that the tickle method will be called by the specified interval. This is affected by two factors - latencies in Java threads or other activity in the runtime that does not allow the invocation of the timer's tickle, and the amount of time that the the tickle method itself takes to execute. In these cases (ie. the next tickle is late) it will be called at the earliest possible time. For example if you have a tickle interval of 100 msecs and the previous tickle took 150msecs to execute, then the next tickle will be given at the earlies possible return. A consequent tickle to that will be in the interval specified or ASAP if this consequent tickle takes longer than the specified time. It delegates its tasking requirements to the TaskAllMovies class.

See Also:: TimeBase, Ticklish, Timeable, TaskAllMovies

Timer(int, int): Create a Timer.
Timer(int, int, Ticklish): Create a Timer.
Timer(int, int, Ticklish, Movie): Create a Timer.

finalize(): The finalize method deactivates the timer.
getPeriod(): Returns the current period (number of scale ticks) of the Timer's tickle notification.
getRate(): Returns the current rate of this Timer - this is the Timer's TimeBase rate.
getScale(): Returns the current scale of the Timer's tickle notification.
getTicklish(): Returns the current target of the Targetable object - this is the object that the Targetable will act upon.
getTimeBase(): Returns the current time base that provides the time foundation of this object.
isActive(): Returns the current active state of the Timer.
isTickling(): Returns true if the Timer, when active, will tickle or false if the Timer, when active, will not tickle.
rescheduleTickle(int, int): This method will reschedule the Timer's callback mechanism to the new scale and period values.
setActive(boolean): Sets the active state of the Timer; only an active Timer will tickle.
setRate(float): Sets the Timeable's playback rate.
setTickling(boolean): Sets the tickle state of the Timer.
tickle(float, int): When the time from zero (or a timeChanged time value, or the previous tickle time) that is specified by the scale and period of the Timer has elapsed the timer calls the tickle method.
timeChanged(int): This is called by the Timer itself when the time base of the Timer has changed, through being reset to a new time or through the effective rate of the Timer changing from positive to negative or vice versa
toString(): Return a string representation of this class.

Timer

 public Timer(int scale,
              int period) throws QTException

Create a Timer.

Parameters:: scale - the scale of the timer's tickle invocation period; period - the number of scale size ticks that elapse between each invocation of the tickle method

Timer

 public Timer(int scale,
              int period,
              Ticklish target) throws QTException

Create a Timer.

Parameters:: scale - the scale of the timer's tickle invocation period; period - the number of scale size ticks that elapse between each invocation of the tickle method; target - the Ticklish target of the Timer - if this is not null then the target's tickle and timeChanged method will be invoked by the Timer.

Timer

 public Timer(int scale,
              int period,
              Ticklish target,
              Movie mov) throws QTException

Create a Timer.

Parameters:: scale - the scale of the timer's tickle invocation period; period - the number of scale size ticks that elapse between each invocation of the tickle method; target - the Ticklish target of the Timer - if this is not null then the target's tickle and timeChanged method will be invoked by the Timer.; mov - the Movie from which the TimeBase of the timer will be derived.

isTickling

 public boolean isTickling()

Returns true if the Timer, when active, will tickle or false if the Timer, when active, will not tickle. This does not indicate whether the Timer is active.

Returns:: a boolean

setTickling

 public void setTickling(boolean flag) throws StdQTException

Sets the tickle state of the Timer. If true then the Timer when active will tickle. If false then the Timer when active will not tickle. This does not activate or deactivate a Timer.

Parameters:: flag - a boolean

getTicklish

 public Ticklish getTicklish()

Returns the current target of the Targetable object - this is the object that the Targetable will act upon.

Returns:: the current target

getTimeBase

 public final TimeBase getTimeBase()

Returns the current time base that provides the time foundation of this object.

Returns:: a TimeBase

rescheduleTickle

 public synchronized void rescheduleTickle(int scale,
                                           int period) throws QTException

This method will reschedule the Timer's callback mechanism to the new scale and period values. Scale cannot be zero. A zero period will disable any tickle. This will have the side-effect of resetting the isTickling state to true, so can be used to both reschedule a tickle call and ensure that a tickle will be sent.

Parameters:: scale - the new scale of the Timer's tickle notification; period - the number of scale ticks that will elapse between notifications.

getScale

 public int getScale()

Returns the current scale of the Timer's tickle notification.

Returns:: the scale

getPeriod

 public int getPeriod()

Returns the current period (number of scale ticks) of the Timer's tickle notification.

Returns:: the scale

getRate

 public float getRate()

Returns the current rate of this Timer - this is the Timer's TimeBase rate. This may not be the actual or effective rate that the timer is ticking at if its TimeBase is slaved to another TimeBase

Returns:: the current rate

setRate

 public void setRate(float rate)

Sets the Timeable's playback rate. Typically a rate of zero will mean that the player is stopped, a positive value that the player is playing forwards. If the object implements the Playable interface setting a negative value will play the player backwards. However, if the object does not have a time line then a negative value will continue to play the object in a forwards direction.

Parameters:: rate - the new playback rate.

setActive

 public synchronized void setActive(boolean flag) throws QTException

Sets the active state of the Timer; only an active Timer will tickle.

Parameters:: flag - fi true the Timer is active, if false it is inactive

isActive

 public boolean isActive()

Returns the current active state of the Timer.

Returns:: true if the Timer is active, or false if it is not

toString

 public String toString()

Return a string representation of this class.

Overrides:: toString in class Object

timeChanged

 protected void timeChanged(int newTime) throws QTException

This is called by the Timer itself when the time base of the Timer has changed, through being reset to a new time or through the effective rate of the Timer changing from positive to negative or vice versa

Parameters:: newTime - the new time of the Timer's time line expressed in the Ticklish.kScale

tickle

 protected boolean tickle(float er,
                          int time) throws QTException

When the time from zero (or a timeChanged time value, or the previous tickle time) that is specified by the scale and period of the Timer has elapsed the timer calls the tickle method. The Timer will only call this method if the Timer has an effective rate that is not zero.

Parameters:: er - the effective or actual rate that the timer is ticking at.; time - the current time of the time base expressed in the Ticklish.kScale
Returns:: true if the Timer should remain active and tickle again or false if it should become inactive.

finalize

 protected void finalize() throws Throwable

The finalize method deactivates the timer.

Overrides:: finalize in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index